Section 3.1.5.2
Color Keywords

The older keyword method of specifying a color is still useful and many users prefer it. Like a color vector, you begin with the optional keyword color. This is followed by any of five additional keywords red, green, blue, filter, or transmit. Each of these component keywords is followed by a float expression. For example

color red 1.0 green 0.5

This specifies a color whose red component is 1.0 or 100% of full intensity and the green component is 0.5 or 50% of full intensity. Although the blue, filter and transmit components are not explicitly specified, they exist and are set to their default values of 0. The component keywords may be given in any order and if any component is unspecified its value defaults to zero.

Section 3.1.5.3
Color Identifiers

Color identifiers may be declared to make scene files more readable and to parameterize scenes so that changing a single declaration changes many values. A color identifier is declared as either of the following...

#declare IDENTIFIER = COLOR_VECTOR #declare IDENTIFIER = COLOR_KEYWORDS...

Where IDENTIFIER is the name of the identifier up to 40 characters long and COLOR_VECTOR or COLOR_KEYWORDS are any valid color specifications as described in the two previous sections of this document. Here are some examples...

#declare White = rgb <1,1,1> #declare Cyan = color blue 1.0 green 1.0 #declare Weird = rgb <Foo*2,Bar-1,Bob/3> #declare LightGray = White*0.8 #declare LightCyan = Cyan red 0.6

As the LightGray example shows, you do not need any color keywords when creating color expressions based on previously declared colors. The last example shows you may use a color identifier with the keyword style syntax. WARNING: Make sure the identifier is first before any other component keywords.

Like floats and vectors, you may re-define colors throughout a scene but the need to do so is rare.

Section 3.1.5.4
Color Operators

Color vectors may be combined in expressions the same as float or vector values. Operations are performed on a component-by-component basis. For example rgb <1.0, 0.5 0.2> * 0.9 evaluates the same as rgb <1.0, 0.5 0.2> * <0.9, 0.9, 0.9> or rgb <0.9, 0.45, 0.18>. Other operations are done on a similar component-by-component basis.

You may use the dot operator to extract a single component from a color. Suppose the identifier "Shade" was previously defined as a color. Then Shade.red is the float value of the red component of Shade. Similarly Shade.green Shade.blue Shade.filter and Shade.transmit extract the float value of the other color components.

Section 3.1.5.5
Common Color Pitfalls

The variety and complexity of color specification methods can lead to some common mistakes. Here are some things to consider when specifying a color.

When using filter transparency, the colors which come through are multiplied by the primary color components. For example if grey light such as rgb<0.9,0.9,0.9> passes through a filter such as rgbf<1.0,0.5,0.0.1.0> the result is rgb<0.9,0.45,0.0> with the red let through 100%, the green cut in half from 0.9 to 0.45 and the blue totally blocked. Often users mistakenly specify a clear object by

color filter 1.0

but this has implied red, green and blue values of zero. You've just specified a totally black filter so no light passes through. The correct way is either:

color red 1.0 green 1.0 blue 1.0 filter 1.0

or:

color transmit 1.0

In the 2nd example it doesn't matter what the rgb values are. All of the light passes through untouched.

Another pitfall is the use of color identifiers and expressions with color keywords. For example...

color My_Color red 0.5

this substitutes whatever was the red component of My_Color with a red component of 0.5 however...

color My_Color + red 0.5

adds 0.5 to the red component of My_Color and even less obvious...

color My_Color * red 0.5

this cuts the red component in half as you would expect but it also multiplies the green, blue, filter and transmit components by zero! The part of the expression after the multiply operator evaluates to rgbft<0.5,0,0,0,0> as a full 5 component color.

The following example results in no change to My_Color.

color red 0.5 My_Color

that is because the identifier fully overwrites the previous value. When using identifiers with color keywords, the identifier should be first.

One final issue, some POV-Ray syntax allows full color specifications but only uses the rgb part. In these cases it is legal to use a float where a color is needed. For example:

finish{ambient 1}

The ambient keyword expects a color so the value 1 is promoted to <1,1,1,1,1> which is no problem. However

pigment{color 0.4}

is legal but it may or may not be what you intended. The 0.4 is promoted to <0.4,0.4,0.4,0.4,0.4> with the filter and transmit set to 0.4 as well. It is more likely you wanted...

pigment{color rgb 0.4}

in which case a 3 component vector is expected. Therefore the 0.4 is promoted to <0.4,0.4,0.4,0.0,0.0> with default zero for filter and transmit.

Section 3.1.6
Strings

The POV-Ray language requires you to specify a string of characters to be used as a file name, text for messages or text for a text object. Strings may be specified using literals, identifiers or functions which return string values. Although you cannot build string expressions from symbolic operators such as are used with floats, vectors, or colors, you may perform various string operations using string functions. Some application of strings in POV-Ray allow for non-printing formatting characters such as newline or form-feed.

Section 3.1.6.1
String Literals

String literals begin with a double quote mark " which is followed by up to 256 printable ASCII characters and are terminated by another double quote mark. The following are all valid string literals:

  "Here"   "There"    "myfile.gif"    "textures.inc"

Section 3.1.6.2
String Identifiers

String identifiers may be declared to make scene files more readable and to parameterize scenes so that changing a single declaration changes many values. An identifier is declared as follows...

#declare IDENTIFIER = STRING

Where IDENTIFIER is the name of the identifier up to 40 characters long and STRING is a string literal, string identifier or function which returns a string value. Here are some examples...

#declare Font_Name = "ariel.ttf" #declare Inc_File = "myfile.inc" #declare Name = "John" #declare Name = concat(Name," Doe")

As the last example shows, you can re-declare a string identifier and may use previously declared values in that re-declaration.

Section 3.1.7
Built-in Identifiers

There are several built-in float and vector identifiers. You can use them to specify values or to create expressions but you cannot re-declare them to change their values.

Section 3.1.7.1
Constant Built-in Identifiers

Most built-in identifiers never change value. The are defined as though the following lines were at the start of every scene.

#declare pi = 3.1415926535897932384626 #declare true = 1 #declare yes = 1 #declare on = 1 #declare false = 0 #declare no = 0 #declare off = 0 #declare u = <1,0> #declare v = <0,1> #declare x = <1,0,0> #declare y = <0,1,0> #declare z = <0,0,1> #declare t = <0,0,0,1>

The built-in float identifier pi is obviously useful in math expressions involving circles.

The built-in float identifiers on off yes no true false are designed for use as boolean constants.

The built-in vector identifiers x y and z provide much greater readability for your scene files when used in vector expressions. For example....

plane {y,1} // The normal vector is obviously "y". plane {<0,1,0>,1} // This is harder to read. translate 5*x // Move 5 units in the "x" direction. translate <5,0,0> // This is less obvious.

An expression like 5*x evaluates to 5*<1,0,0> or <5,0,0>.

Section 3.1.7.2
Built-in Identifier 'clock'

A built-in float identifier clock is used to control animations in POV-Ray. Unlike some animation packages, the action in POV-Ray animated scenes do not depend upon the integer frame numbers. Rather you should design your scenes based upon the float identifier clock. For non-animated scenes its default value is 0 but you can set it to any float value using the INI file option Clock=nn.nnn or the command-line switch +Knn.nnn to pass a single float value your scene file.

Other INI options and switches may be used to animate scenes by automatically looping through the rendering of frames using various values for clock. By default, the clock value is 0 for the initial frame and 1 for the final frame. All other frames are interpolated between these values. For example if your object is supposed to rotate one full turn over the course of the animation, you could specify rotate 360*clock*y Then as clock runs from 0 to 1, the object rotates about the y-axis from 0 to 360 degrees.

Although the value of clock will change from frame-to-frame, it will never change throughout the parsing of a scene.

See "Animation Options" for more details.

Section 3.1.7.3
Built-in Identifier 'version'

The built-in float identifier version contains the current setting of the version compatibility option. Although this value defaults to 3 which is the current POV-Ray version number, the initial value of version may be set by the INI file option Version=n.nn or by the +MVn.nn command-line switch. This tells POV-Ray to parse the scene file using syntax from an earlier version of POV-Ray.

The INI option or switch only affects the initial setting. Unlike other built-in identifiers, you may change the value of version throughout a scene file. You do not use #declare to change it. The #version language directive is used to change modes. Such changes may occur several times within scene files.

Together with the built-in version identifier, the #version directive allows you to save and restore the previous values of this compatibility setting. For example suppose MYSTUFF.INC is in version 1 format. At the top of the file you could put:

#declare Temp_Vers = version // Save previous value #version 1.0 // Change to 1.0 mode ... // Version 1.0 stuff goes here... #version Temp_Vers // Restore previous version

Section 3.1.8
Functions

POV-Ray defines a variety of built-in functions for manipulating floats, vectors and strings. The functions are listed grouped according to their usage and not by the type of value they return. For example vdot computes the dot product of two vectors and is listed as a vector function even though it returns a single float value.

Function calls consist of a keyword which specifies the name of the function followed by a parameter list enclosed in parentheses. Parameters are separated by commas. For example:

keyword(param1,param2)

Functions evaluate to values that are floats, vectors or strings and may be used in expressions or statements anywhere that literals or identifiers of that type may be used.